home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / desktop / neop302a.zoo / data5 < prev    next >
Text File  |  1993-02-09  |  9KB  |  196 lines
  1.                         JARxxx:  Cookie Jar Manager
  2.                                 by Dan Wilga
  3.                       Copyright 1992, Gribnif Software
  4.                       
  5. This program may be freely distributed, even with commercial products, so
  6. long as this documentation file is included, and both it and the program
  7. are unmodified.
  8.  
  9.  
  10. What is the Cookie Jar, anyway?
  11. ------------------------------
  12.  
  13. When Atari created TOS 1.60, they added a feature to the operating system
  14. which had been needed for some time. It allows programs to store
  15. information in a place where any other program can look for it. This Cookie
  16. Jar is very useful for things like an AUTO folder program which wants to be
  17. able to leave some information around for a companion desk accessory to
  18. look at. Also, newer versions of the operating system use cookies to tell
  19. programs what types of hardware the computer has.
  20.  
  21.  
  22. Fine, so why do I need this program?
  23. -----------------------------------
  24.  
  25. When Atari documented how to use the Cookie Jar, it outlined how
  26. programmers should create new cookies and how to see what value a
  27. particular cookie has. Unfortunately, the procedure for doing this is not
  28. all that simple. The result was that some programs either go about it
  29. half-heartedly, or do not work correctly in all cases.
  30.  
  31. What JARxxx does is take the "dirty work" away and simplify the whole
  32. process of using the Cookie Jar. It provides a standard way for programs to
  33. look for cookies and create new ones. It also establishes a new jar, as
  34. large as you want it to be, for all future programs to use.
  35.  
  36. If you received this program as part of another package, you will probably
  37. need it in order for the other program to run properly. Even if you do not
  38. have a program which takes advantage of the code in JARxxx to look for and
  39. create new cookies, you can still benefit from its ability to enlarge the
  40. Cookie Jar, since some programs which create cookies will give an error
  41. message when the Cookie Jar is full, rather than making it larger.
  42.  
  43.  
  44. Installation
  45. ------------
  46.  
  47. JARxxx is very easy to install. All you have to do is copy JARXXX.PRG into
  48. the AUTO folder of the disk you normally boot from. Then, rename the
  49. program so that the "XXX' is a number. This number, which is the quantity
  50. of new cookies to make space for in the jar, can be anywhere from 0 to 999.
  51.  
  52. Usually, a program will only create one cookie for itself, if it creates
  53. any at all. A value of 10 extra cookies will probably be more than enough
  54. for most people. They take up very little memory (8 bytes each), so don't
  55. worry about making the number too large.
  56.  
  57. If you make this number too small, a program may quit with a message like
  58. "Not enough room in cookie jar". If this happens, you can either run
  59. JARxxx.PRG again from the desktop (to double the number of entries), or
  60. increase the number by changing the name of the file in the AUTO folder.
  61.  
  62. Probably the most common type of program to use the Cookie Jar is one which
  63. runs in the AUTO folder. For this reason, JARxxx must be set to run before
  64. all the other AUTO folder programs. To accomplish this, there is a program
  65. called AUTOFRST which is also included with JARxxx.
  66.  
  67. AUTOFRST will take whatever program you tell it to and reposition it so
  68. that it will be the first program the operating system loads from the AUTO
  69. folder.  You tell AUTOFRST which program to make first by giving it the full
  70. path of that file on the TTP commandline. For instance, if you tell it
  71. "c:\auto\jar16.prg", then JAR16.PRG will be moved to the first position.
  72.  
  73. AUTOFRST can actually be used to reorder the files in any directory, not
  74. just the AUTO folder. It can also be given a list of filenames, like this:
  75.  
  76.   c:\auto\jar16.prg xboot.prg neoload.prg templmon.prg
  77.  
  78.  
  79. Technical Stuff
  80. ---------------
  81.  
  82. The Cookie Jar is pointed to by a variable called _p_cookies, which is
  83. located at $5A0. If there is no jar installed, this memory location
  84. contains a null pointer. Each cookie in the jar is two longwords in size:
  85.  
  86.                      longword 1  longword 2
  87.                    -------------------------
  88.         Cookie #1  | ID Number |   Value   |
  89.                    -------------------------
  90.         Cookie #2  | ID Number |   Value   |
  91.                    -------------------------
  92.         ...
  93.                    -------------------------
  94.         Cookie #n  | ID Number |   Value   |
  95.                    -------------------------
  96.     Length Cookie  | 0 (long)  | Jar Size  |
  97.                    -------------------------
  98.         
  99. The first longword in a cookie is an ID number. This should somehow
  100. describe what program installed the cookie. A common practice is to use a
  101. longword whose ASCII value is an abbreviation for the program.  For
  102. example, JARxxx installs a cookie whose ID is "CJar" ($434A6172).  Atari
  103. has reserved all ID's beginning with "_" for use by the operating system.
  104. You should not use ID's beginning with this character.
  105.  
  106. The "Value" field of a cookie can contain any information at all, but since
  107. there are only four bytes of space, the most common thing to do is to use
  108. this to store a pointer to a larger structure which can hold more
  109. information.
  110.  
  111. The last cookie in the jar has an ID of zero (long). This indicates the end
  112. of the cookie jar. The "value" of this cookie is actually a longword
  113. indicating how many entries the entire jar can hold. This number does NOT
  114. include the length cookie, itself. Therefore, a jar large enough for 10 new
  115. cookies must actually be 11 entries (or 22 longwords) in size.
  116.  
  117.  
  118. Programming Using JARxxx
  119. ------------------------
  120.  
  121. JARxxx works by first copying the old Cookie Jar to a new location, if
  122. necessary. This depends on the number of entries requested. If the number
  123. of requested entries is less than the current number of empty entries, the
  124. jar is not changed. This means that if you just want to install the jar
  125. management code without increasing the jar, you simply need to request 0
  126. entries. JARxxx also intercepts trap #14 (XBIOS) and the reset vector (to
  127. clean up the Cookie Jar for older versions of the operating system.)
  128.  
  129. If you want to use JARxxx's routines in your own program, here is all you
  130. need to know. There is a new XBIOS routine ($434A) which is installed by
  131. JARxxx to handle requests by a program. A C language binding:
  132.  
  133.         int CJar( int mode, long cookie, long *value )
  134.  
  135. Mode 0 will retrieve the "cookie" and store its value in the longword
  136. pointed to by the long pointer.  If the long pointer is null (zero), then
  137. the value is not stored anywhere.  The value $6172 is returned if the
  138. search was successful; 0 is returned if the cookie was not found. Any other
  139. value greater than zero can be assumed to mean that JARxxx is not
  140. installed.  Values less than zero are currently reserved.
  141.  
  142. This mode can, and should be, used to determine if JARxxx is installed
  143. before actually creating a new cookie.  If the "cookie" parameter is
  144. $434A6172 ("CJar") and the number $6172 is returned, then JARxxx is
  145. installed.  In this situation, any other return value means JARxxx is not
  146. installed.  If the "value" pointer is not null (zero), then the longword
  147. pointed to by it is modified to contain the following information:
  148.  
  149.         high word, high byte:   Version number, starting at $01.
  150.  
  151.         high word, low byte:    An unsigned byte indicating the number of
  152.                                 cookie jar entries specified by the user. A
  153.                                 value of zero means 256 or more.
  154.  
  155.         low word, high byte:    An unsigned byte indicating the number of
  156.                                 cookie jar entries actually allocated.
  157.                                 This includes any cookie jar entries which
  158.                                 already existed when JARxxx first ran.  A
  159.                                 value of zero means 256 or more.
  160.  
  161.         low word, low byte:     An unsigned byte indicating the number of
  162.                                 cookie jar entries currently being used.  A
  163.                                 value of zero means 256 or more.